天翼云客户端加密模块接口文档

概述

客户端加密模块SDK是一个用于数据加密、解密和签名验证的 Java 库，支持多种加密算法和密钥管理策略。SDK提供了简单易用的 API，帮助开发者快速实现数据的安全加密、解密和签名验证操作。

安装与配置

1. 依赖库部署

使用SDK前需将 C 依赖库放入相应的路径下，否则无法调用相关功能。

Linux 环境

将文件夹 lib 中对应版本的 xxx.so 放置对应目录下：

64位系统：库文件放入 /lib64 目录下
32位系统：库文件放入 /usr/lib 目录下

Windows 环境

将文件夹 lib 中对应的版本的 xxx.dll 放置对应目录下：

64位系统：DLL 文件存放在 C:\Windows\System32 目录或者 jar 包同级目录下
32位系统：DLL 文件存放在 C:\Windows\SysWOW64 目录或者 jar 包同级目录下

2. Java 的 jar 包集成

应用系统新增依赖配置

# 安装加密软模块sdk包
mvn install:install-file -Dfile=lib/TASSLAPI-v1.5.2-20251215.1.jar   -DgroupId=org.tasslsdk -DartifactId=tassl -Dversion=1.5.2 -Dpackaging=jar
# 安装kms终端节点sdk
mvn install:install-file -Dfile=lib/ctyun_kms_sdk_java.jar -DgroupId=org.kmssdk -DartifactId=ctyun_kms_sdk_java -Dversion=1.2.1.1 -Dpackaging=jar

添加依赖

<dependency>
    <groupId>org.tasslsdk</groupId>
    <artifactId>tassl</artifactId>
    <version>1.5.2</version>
</dependency>

其他依赖jar包信息：

annotations-13.0.jar
hutool-all-5.8.5.jar
kotlin-stdlib-1.4.0.jar
okhttp-4.9.0.jar
okio-2.8.0.jar

3. 权限说明

注意：软模块初始化需要 root 权限，获取失败程序结束

核心类与方法

`KmsSecurityManager` 类

用于激活软模块并创建激活文件。

主要方法

public static KmsSecurityManager getInstance(String license, String keyFilePath)：激活软模块并创建激活文件，返回初始化的对象。

`TasslApi` 类

TASSL 接口的核心类，提供了加密、解密和签名验证的主要功能。

主要方法

public static synchronized TasslApi getInstance(String ak, String sk, String ipport, String keyFilePath)：初始化 TASSL 接口，加载天翼云的 KMS 库，随机生成 SM2 密钥对。
public String getSymmetricKey(String CmkUuid, String alg)：上传 SM2 公钥，获取 KMS 产生的对称密钥。
public byte[] symmetricEncryption(String keyCipher, String keyAlg, byte[] iv, byte[] inData)：对称密钥加密数据。
public byte[] symmetricDecryption(String keyCipher, String keyAlg, byte[] iv, byte[] inData)：对称密钥解密数据。
public void symmetricEncryptionFile(String keyCipher, String keyAlg, byte[] iv, String inFilePath, String outFilePath)：对称密钥文件加密。
public void symmetricDecryptionFile(String keyCipher, String keyAlg, byte[] iv, String inFilePath, String outFilePath)：对称密钥文件解密。
public ArrayList<byte[]> SM4GCMEncrypt(String keyCipher, byte[] inData, byte[] iv)：SM4-GCM 加密。
public byte[] SM4GCMDecrypt(String keyCipher, byte[] inData, byte[] tag, byte[] iv)：SM4-GCM 解密。
public void SM4GCMEncryptFile(String keyCipher, byte[] iv, String inFilePath, String outFilePath)：SM4-GCM 文件加密。
public void SM4GCMDecryptFile(String keyCipher, byte[] iv, String inFilePath, String outFilePath)：SM4-GCM 文件解密。
public byte[] generateHMACSM3(String keyCipher, byte[] inData)：SM3-HMAC 计算。
public boolean verifySM2Signature(byte[] SM2Cert, String signature, byte[] inData)：SM2 验签。

支持的功能说明

1. 联网激活

功能介绍：激活软模块并创建激活文件；激活目录要求有写入权限
返回：初始化的对象
抛出：Exception
请求参数：
名称类型描述
license String 软模块激活码
keyFilePath String 激活文件存储目录

名称	类型	描述
license	String	软模块激活码
keyFilePath	String	激活文件存储目录

2. 初始化

功能介绍：初始化 TASSL 接口，加载天翼云的 KMS 库，随机生成 SM2 密钥对
返回：初始化的对象
抛出：Exception
请求参数：
名称类型描述
ak String 鉴权的 AK
sk String 鉴权的 SK
ipport String KMS 的 ip 和端口
keyFilePath String 保存密钥文件的路径

名称	类型	描述
ak	String	鉴权的 AK
sk	String	鉴权的 SK
ipport	String	KMS 的 ip 和端口
keyFilePath	String	保存密钥文件的路径

3. 产生数据密钥

功能介绍：上传 SM2 公钥，获取 KMS 产生的对称密钥
返回：主密钥加密的密文
抛出：Exception
请求参数：
名称类型描述
CmkUuid String 主密钥的 UID
alg String 需要产生的密钥算法：取值 AES_128、AES_256、Ctyun_SM4

名称	类型	描述
CmkUuid	String	主密钥的 UID
alg	String	需要产生的密钥算法：取值 AES_128、AES_256、Ctyun_SM4

4. 对称密钥加密

功能介绍：对称密钥加密数据
返回：加密后的密文
抛出：Exception

请求参数：

名称	类型	描述
keyCipher	String	加密密钥
keyAlg	String	加密算法，支持：AES_128/ECB/PKCS5Padding、AES_256/ECB/PKCS5Padding、AES_128/ECB/NoPadding、AES_256/ECB/NoPadding、AES_128/CBC/PKCS5Padding、AES_256/CBC/PKCS5Padding、AES_128/CBC/NoPadding、AES_256/CBC/NoPadding、Ctyun_SM4/ECB/PKCS5Padding、Ctyun_SM4/CBC/PKCS5Padding、Ctyun_SM4/ECB/NoPadding、Ctyun_SM4/CBC/NoPadding
iv	byte[]	非 ECB 模式的初始向量
inData	byte[]	待加密的数据

5. 对称密钥解密

功能介绍：对称密钥解密数据
返回：明文数据
抛出：Exception

请求参数：

名称	类型	描述
keyCipher	String	加密密钥
keyAlg	String	加密算法，支持：AES_128/ECB/PKCS5Padding、AES_256/ECB/PKCS5Padding、AES_128/ECB/NoPadding、AES_256/ECB/NoPadding、AES_128/CBC/PKCS5Padding、AES_256/CBC/PKCS5Padding、AES_128/CBC/NoPadding、AES_256/CBC/NoPadding、Ctyun_SM4/ECB/PKCS5Padding、Ctyun_SM4/CBC/PKCS5Padding、Ctyun_SM4/ECB/NoPadding、Ctyun_SM4/CBC/NoPadding
iv	byte[]	非 ECB 模式的初始向量
inData	byte[]	待解密的数据

6. 对称密钥文件加密

功能介绍：文件加密
返回：加密后的密文文件
抛出：Exception

请求参数：

名称	类型	描述
keyCipher	String	加密密钥
keyAlg	String	加密算法，支持：AES_128/ECB/PKCS5Padding、AES_256/ECB/PKCS5Padding、AES_128/ECB/NoPadding、AES_256/ECB/NoPadding、AES_128/CBC/PKCS5Padding、AES_256/CBC/PKCS5Padding、AES_128/CBC/NoPadding、AES_256/CBC/NoPadding、Ctyun_SM4/ECB/PKCS5Padding、Ctyun_SM4/CBC/PKCS5Padding、Ctyun_SM4/ECB/NoPadding、Ctyun_SM4/CBC/NoPadding
iv	byte[]	非 ECB 模式的初始向量
inFilePath	String	文件输入地址
outFilePath	String	文件输出地址

7. 对称密钥文件解密

功能介绍：文件解密
返回：解密后的明文文件
抛出：Exception

请求参数：

名称	类型	描述
keyCipher	String	加密密钥
keyAlg	String	加密算法，支持：AES_128/ECB/PKCS5Padding、AES_256/ECB/PKCS5Padding、AES_128/ECB/NoPadding、AES_256/ECB/NoPadding、AES_128/CBC/PKCS5Padding、AES_256/CBC/PKCS5Padding、AES_128/CBC/NoPadding、AES_256/CBC/NoPadding、Ctyun_SM4/ECB/PKCS5Padding、Ctyun_SM4/CBC/PKCS5Padding、Ctyun_SM4/ECB/NoPadding、Ctyun_SM4/CBC/NoPadding
iv	byte[]	非 ECB 模式的初始向量
inFilePath	String	文件输入地址
outFilePath	String	文件输出地址

8. SM4-GCM 加密

功能介绍：SM4-GCM 加密
返回：索引 0 - 加密后的密文，索引 1 - 密文的 tag
抛出：Exception
请求参数：
名称类型描述
keyCipher String 加密密钥
inData byte[] 待加密的数据
iv byte[] 初始向量

9. SM4-GCM 解密

功能介绍：SM4-GCM 解密
返回：解密后的明文
抛出：Exception
请求参数：
名称类型描述
keyCipher String 加密密钥
inData byte[] 待解密的数据
tag byte[] GCM 算法的 tag
iv byte[] 初始向量

10. SM4-GCM 文件加密

功能介绍：SM4-GCM 文件加密
返回：无
抛出：Exception
请求参数：
名称类型描述
keyCipher String 加密密钥
iv byte[] 初始向量
inFilePath String 文件输入地址
outFilePath String 文件输出地址

11. SM4-GCM 文件解密

功能介绍：SM4-GCM 文件解密
返回：无
抛出：Exception
请求参数：
名称类型描述
keyCipher String 加密密钥
iv byte[] 初始向量
inFilePath String 文件输入地址
outFilePath String 文件输出地址

12. SM3-HMAC 计算

功能介绍：数据 SM3-计算 HMAC
返回：HMAC
抛出：Exception
请求参数：
名称类型描述
keyCipher String 加密密钥
inData byte[] 待计算的数据

13. SM2 验签

功能介绍：SM2 验签
返回：验签的结果
抛出：Exception
请求参数：
名称类型描述
SM2Cert byte[] SM2 公钥证书
signature String SM2 签名值（Base64）
inData byte[] 签名的源数据

名称	类型	描述
SM2Cert	byte[]	SM2 公钥证书
signature	String	SM2 签名值（Base64）
inData	byte[]	签名的源数据

使用示例

1. 联网激活示例

import com.tassl.api.KmsSecurityManager;

public class ActivationExample {
    public static void main(String[] args) {
        String license = "your_license_key";
        String keyFilePath = "/path/to/key/file";
        KmsSecurityManager manager = KmsSecurityManager.getInstance(license, keyFilePath);
        if (KmsSecurityManager.getGlobalFlag()){
            System.out.println("激活成功");
        }
    }
}

2. 初始化示例

import com.tassl.api.TasslApi;

public class InitializationExample {
    public static void main(String[] args) {
        try {
            // 初始化 TASSL 接口
            String ak = "your_ak";
            String sk = "your_sk";
            String ipport = "kms_ip:port";
            String keyFilePath = "/path/to/key/file";
            TasslApi tasslApi = TasslApi.getInstance(ak, sk, ipport, keyFilePath);
            System.out.println("初始化成功：" + tasslApi);
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("初始化失败");
        }
    }
}

3. 对称密钥加密和解密示例

import com.tassl.api.TasslApi;
import java.util.Base64;

public class SymmetricEncryptionExample {
    public static void main(String[] args) {
        try {
            String ak = "your_ak";
            String sk = "your_sk";
            String ipport = "kms_ip:port";
            String keyFilePath = "/path/to/key/file";
            // 初始化 TASSL 接口
            TasslApi tasslApi = TasslApi.getInstance(ak, sk, ipport, keyFilePath);
            
            // 产生数据密钥
            String cmkUuid = "your_cmk_uuid";
            String alg = "AES_256";
            String keyCipher = tasslApi.getSymmetricKey(cmkUuid, alg);
            System.out.println("数据密钥：" + keyCipher);
            
            // 加密数据
            String keyAlg = "AES_128/CBC/PKCS5Padding";
            byte[] iv = new byte[16]; // 16字节初始向量
            byte[] inData = "Hello, World!".getBytes();
            byte[] encryptedData = tasslApi.symmetricEncryption(keyCipher, "AES_256/ECB/PKCS5Padding", iv, inData);
            System.out.println("加密结果：" + Base64.getEncoder().encodeToString(encryptedData));
            
            // 解密数据
            byte[] decryptedData = tasslApi.symmetricDecryption(keyCipher, "AES_256/ECB/PKCS5Padding", iv, encryptedData);
            System.out.println("解密结果：" + new String(decryptedData));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

异常处理

接口中的方法可能会抛出 Exception 异常，建议在使用时进行捕获和处理。

try {
    // TASSL 接口操作
} catch (Exception e) {
    e.printStackTrace();
    // 处理异常
}

注意事项

确保依赖库文件正确部署到指定目录，否则无法调用相关功能。
软模块初始化需要 root 权限，获取失败程序结束。
激活目录和文件读写路径需要保证有写入权限。
使用 NoPadding 模式时，需要保证待加密的数据是密钥分组算法的整数倍（AES 密钥分组为 16 字节）。
确保 AK、SK 和 KMS 服务地址配置正确，否则无法正常访问 KMS 服务。

支持与反馈

如有任何问题或建议，请联系技术支持团队。

通过以上文档，您可以快速上手使用客户端加密模块，实现数据的安全加密、解密和签名验证操作。

天翼云客户端加密模块 接口文档

概述

安装与配置

1. 依赖库部署

Linux 环境

Windows 环境

2. Java 的 jar 包集成

应用系统新增依赖配置

添加依赖

其他依赖jar包信息：

3. 权限说明

核心类与方法

KmsSecurityManager 类

主要方法

TasslApi 类

主要方法

支持的功能说明

1. 联网激活

2. 初始化

3. 产生数据密钥

4. 对称密钥加密

5. 对称密钥解密

6. 对称密钥文件加密

7. 对称密钥文件解密

8. SM4-GCM 加密

9. SM4-GCM 解密

10. SM4-GCM 文件加密

11. SM4-GCM 文件解密

12. SM3-HMAC 计算

13. SM2 验签

使用示例

1. 联网激活示例

2. 初始化示例

3. 对称密钥加密和解密示例

异常处理

注意事项

支持与反馈

天翼云客户端加密模块接口文档

`KmsSecurityManager` 类

`TasslApi` 类